============
Introduction
============

Sieve_ is a programming language for filtering mail. Sieve scripts are
executed on the mail server when mail is delivered to an inbox, so they
have to be uploaded to the mail server. SieveManager is a command-line
client for doing just that, that is, for uploading, downloading, and
managing remote Sieve scripts using the ManageSieve protocol. It can
also be used as a Python module.

.. warning::
    SieveManager is work-in-progress. The command-line interface,
    the configuration file, and the Python API are subject to change.
    It may also be buggy.

.. _Sieve: http://sieve.info


Example
=======

Upload and activate a Sieve script:

.. code:: none

    $ sievemgr user@imap.foo.example
    sieve://user@imap.foo.example> put script.sieve
    sieve://user@imap.foo.example> activate script.sieve

In Python:

.. code:: python

    from sievemgr import SieveManager

    with SieveManager('imap.foo.example', 'user', 'password') as mgr:
        with open('sieve.script', 'br') as script:
            mgr.putscript(script, script.name)
        mgr.setactive('sieve.script')


Features
========

* Automate logins with:

  * password managers
  * encrypted files
  * `.netrc`_
  * TLS certificates [#untested]_

* Automatic backups

* Tab-completion

* Supports authenticating with:

  * CRAM-MD5
  * EXTERNAL [#undertested]_
  * LOGIN
  * PLAIN
  * SCRAM-SHA-\*
  * SCRAM-SHA-\*-PLUS [#untested]_
  * SCRAM-SHA3-512
  * SCRAM-SHA3-512-PLUS [#untested]_

* System administrator-friendly

  * Comfortable proxy authentication (with Sieve URLs and :sievecmd:`su`).
  * Detailled but readable session logs.
  * Highly configurable.

* Complies fully with :rfc:`5804`. [#fullcomp]_

* Supports TLS `server name indication`_.

* Supports IPv6.


.. [#untested] Untested.

.. [#fullcomp] Full compliance requires dnspython_.

.. [#undertested] Needs more testing.


.. _`.netrc`: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html

.. _SRV: https://en.wikipedia.org/wiki/SRV_record

.. _`server name indication`: https://en.wikipedia.org/wiki/Server_Name_Indication

.. _dnspython: https://www.dnspython.org/


Licence
=======

Copyright 2023 and 2024  Odin Kroeger

SieveManager is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the FreeSoftware Foundation, either version 3 of the License, or (at
your option) any later version.

SieveManager is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the :doc:`GNU General Public License <licence>` for more details.

You should have received a copy of the GNU General Public License
along with SieveManager. If not, see <https://www.gnu.org/licenses/>.


.. toctree::
   :hidden:
   :titlesonly:

   install
   sievemgr
   sieverc
   module
   security
   bugs
   Change log <changelog>
   Licence <licence>
   contact
   genindex
